What

Pilots the repo structure-lock (ArchUnit-style FREEZE of the root file/folder layout) on the umbrella repo. Closes #209 once the owner sets the required check (below).

It blocks — when a disallowed/forbidden file appears at the root (e.g. a stray dated tracking doc), the PR's structure-check goes red. It does not silently auto-move anything.

Depends on Rollingcat-Software/.github#2 (the reusable workflow + stdlib check script). Merge that PR first, or the caller's uses: ref won't resolve.

Contents

The forbidden patterns encode the convention "tracking → GitHub issues, NOT root docs":

forbidden_root_patterns:
  - '.*_(AUDIT|REVIEW|FINDINGS|REGISTER|TRIAGE|SWEEP|STATUS|SESSION|RECONCILIATION)_.*\.md$'
  - '.*_\d{4}-\d{2}-\d{2}.*\.md$'
  - '^(TODO|ROADMAP|BACKLOG|OPERATOR_TODO|PERSONAL_TODO).*\.md$'

Proof

# clean current root
$ python3 check_repo_structure.py --root .
Repo structure-lock PASSED — root layout matches .repo-structure.yml.   (exit 0)

# planted dummy
$ : > TEST_AUDIT_2026-06-13.md
$ python3 check_repo_structure.py --root .
Repo structure-lock FAILED (1 violation):
  - FORBIDDEN: root entry 'TEST_AUDIT_2026-06-13.md' matches forbidden pattern
    /.*_(AUDIT|REVIEW|FINDINGS|REGISTER|TRIAGE|SWEEP|STATUS|SESSION|RECONCILIATION)_.*\.md$/
(exit 1)
# dummy removed — back to PASS.

Local use

pip install pre-commit        # or pipx
./.pre-commit-install         # installs gitleaks + repo-structure in parent + submodules
# now `git commit` runs the structure-lock locally before accepting the commit.
# one-off:  python3 -m ... or run the hook via `pre-commit run repo-structure --all-files`

Rollout to the 7 submodules

Each submodule gets the same two files, frozen from its own root:

1. In a clean clone of the submodule (gh repo clone Rollingcat-Software/<repo>), add .repo-structure.yml listing exactly the current root files/dirs (the frozen baseline) + the same forbidden_root_patterns block above + required_files (at least README.md).
2. Add .github/workflows/structure-check.yml:

   name: structure-check
   on:
     pull_request:
   jobs:
     repo-structure:
       uses: Rollingcat-Software/.github/.github/workflows/repo-structure.yml@main

3. (Optional) add the pre-commit hook to the submodule's .pre-commit-config.yaml:

   - repo: https://github.com/Rollingcat-Software/.github
     rev: main
     hooks:
       - id: repo-structure

4. Open a PR; confirm structure-check passes on the clean root.

The 7 submodules: identity-core-api, biometric-processor, web-app, client-apps, spoof-detector, docs, practice-and-test.

One manual OWNER step (makes it actually block)

After this PR's structure-check has run at least once (so GitHub knows the check name), add it as a required status check on master:

# adds "structure-check" to existing required checks (keep review requirement)
gh api -X PATCH repos/Rollingcat-Software/FIVUCSAS/branches/master/protection/required_status_checks \
  -f strict=false -f 'checks[][context]=structure-check'

# verify
gh api repos/Rollingcat-Software/FIVUCSAS/branches/master/protection/required_status_checks

(The check context surfaces as structure-check — the caller job name. If GitHub shows it nested as repo-structure / structure-check, use that exact string. Confirm the displayed name on the first PR run, then add it.) Repeat per submodule on its default branch (main).

Do not merge until reviewed.